id: task-120 title: Add offline mode configuration for remote operations status: Done assignee: [] created_date: '2025-07-07' updated_date: '2025-07-07' labels:

• enhancement
• offline
• config dependencies: [] priority: high

Description

Backlog.md currently performs git fetch operations silently in the background when loading remote tasks and generating task IDs. When network connectivity is unavailable, these operations fail silently with errors only visible in debug mode. Users working offline need better visibility into connectivity issues and explicit control over when remote operations are attempted.

Acceptance Criteria

• [x] Add a remoteOperations config option (default: true) to enable/disable remote git operations
• [x] Display informative warnings when remote fetch fails due to network connectivity (not just in debug mode)
• [x] Implement graceful fallback messaging when remote tasks cannot be loaded
• [x] Ensure backlog board, backlog board view, and backlog board export commands work seamlessly when remote operations are disabled
• [x] Task ID generation continues to work when remote operations are disabled (using only local branches)
• [x] Config can be set via backlog config set remoteOperations false

Technical Notes

Current Behavior:

• loadRemoteTasks() in src/core/remote-tasks.ts calls gitOps.fetch() but only shows errors in debug mode
• generateNextId() in src/cli.ts performs git fetch for ID uniqueness but suppresses network errors
• Board commands load remote tasks in parallel but fail silently when offline

Proposed Implementation:

• Add remoteOperations to config schema with validation
• Add remoteOperations config value to migration logic for existing projects
• Modify GitOperations.fetch() to check config before attempting remote operations
• Enhance error handling to distinguish network vs. other git errors and provide user-friendly messaging
• Update loadRemoteTasks() and generateNextId() to respect the config setting

Implementation Plan

1. Add config schema field - Update BacklogConfig interface to include remoteOperations?: boolean
2. Update migration logic - Add default value true in config-migration.ts and check for field in needsMigration()
3. Enhance GitOperations - Modify fetch() to check config and add network error detection
4. Update core functions - Modify loadRemoteTasks() and generateNextId() to respect config
5. Update CLI commands - Add support in config get/set/list commands
6. Add comprehensive tests - Unit tests for offline behavior and integration tests for full workflow
7. Update documentation - Ensure config commands show the new option

Implementation Notes

• Configuration approach chosen over CLI flags - Using a config value (remoteOperations) provides a better user experience than requiring --offline flags on every command
• Default value is true - To maintain backward compatibility, remote operations are enabled by default
• Network error detection - Added intelligent error pattern matching to distinguish network errors from other git errors (e.g., "could not resolve host", "connection refused", "network is unreachable")
• Graceful degradation - When offline or when remote operations are disabled, the system continues to work with local data only
• Migration handling - The migration logic filters out undefined values to ensure defaults are properly applied
• Test coverage - Created two comprehensive test suites: offline-mode.test.ts for unit tests and offline-integration.test.ts for full workflow testing
• Config is loaded lazily - Since the Core constructor can't be async, config is loaded when needed via ensureConfigLoaded()
• Parameter naming - Changed config parameter in loadRemoteTasks to userConfig to avoid variable shadowing